//--------------------------------------------------------------------------
// 
//  Copyright (c) Chili Software.  All rights reserved. 
// 
//  File: IPopulateHelperExtended.cs
//
//  Description: Extended Interface for manually populating persistent 
//               objects.
// 
//--------------------------------------------------------------------------

using System;
using System.Collections.Generic;
using System.Text;

namespace Chili.Opf3
{
	/// <summary>
	/// This interface that is implemented by objects that are populated manually.
	/// </summary>
	/// <remarks>
	/// 	<para>This interface is implemented by classes that won't let the framework
	///     automatically populate them with data or retrieve data from them via reflection.</para>
	/// 	<para>If the framework encounters a persistent object that implements this
	///     interface it gives the content of the field from the storage (in combination with
	///     the name of the property that is mapped to that field) as value to the class. The
	///     class itself has to populate the property in an appropriate way.</para>
	/// 	<para><b>Attention:</b> Throw an exception if something goes wrong while manually
	///     populating the object. This will solve problems like loss of data etc.</para>
	/// </remarks>
	/// <example>
	///     The following example shows how to implement the interface. 
	///     <code lang="CS">
	/// [Persistent("USER")]
	/// public class User : IPopulateHelperExtended
	/// {
	///     public bool PropertyIsHandled(string propertyName)
	///     {
	///         switch(propertyName)
	///         {
	///             case "Name":
	///             case "ID":
	///             // ... Other properties.
	///                 return true;
	///             default:
	///                 return false;
	///         }
	///     }
	/// 
	///     public object this[string propertyName]
	///     {
	///         get
	///         {
	///             switch(propertyName)
	///             {
	///                 case "Name":
	///                     return Name;
	///                 // ... Other properties.
	///                 default:
	///                     throw new Exception();
	///             }
	///         }
	///         set
	///         {
	///             switch(propertyName)
	///             {
	///                 case "Name":
	///                     Name = value;
	///                     break;
	///                 // ... Other properties.
	///                 default:
	///                     throw new Exception();
	///             }
	///         }
	///     }
	///  
	///     // ... Other properties and code.
	/// }
	///     </code>
	/// </example>
	public interface IPopulateHelperExtended : IPopulateHelper
	{
		/// <summary>
		/// Returns whether the property is handled by the interface.
		/// </summary>
		/// <param name="propertyName">The name of the property that is checked for being handled.</param>
		/// <returns>True if the property is handled by the interface; otherwise false.</returns>
		bool PropertyIsHandled(string propertyName);
	}
}
